home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
graphic
/
stk100.zip
/
STK.DOC
< prev
next >
Wrap
Text File
|
1990-10-20
|
38KB
|
910 lines
**********************************************************************
This file is part of
STK -- The sprite toolkit -- version 1.0
Copyright (C) Jari Karjala 1990
The sprite toolkit (STK) is a FreeWare toolkit for creating high
resolution sprite graphics with PCompatible hardware. This toolkit
is provided as is without any warranty or such thing. See the file
COPYING and the end of this file for further information.
**********************************************************************
STK -- The Sprite ToolKit -- version 1.0, Oct 20, 1990
Intro
=====
The Sprite Toolkit (STK) contains the following sets of functions,
(each function has its set name in front of it):
SPR lowlevel interface to the sprite functions
SPR_HIT lowlevel collision detection routines
SPR_FIO lowlevel sprite file IO
SPR_ANIM higher level interface to the sprite functions
GR text IO in the graphics mode and keyboard functions
MOUSE INT 33 interface to the mouse functions.
Note that there are two different interface levels to the sprite
routines.
The lowlevel functions provide support for simple sprites which
can be put into the screen, hidden from the screen or deleted.
Collisions between them can be detected. The sprite data can
be read from a file, too.
The higher level interface supports animated sprites which are
composed of simple sprites. These animated sprites can move
automatically along some preset direction vector and act on
different special cases, such as hitting the boundary or other
sprite.
The GR functions provide a familiar set of basic text IO
functions, like putch, put and printf, but these functions work
in the graphics mode. There are also GR functions for direct
reading of the keymap. These functions detect multiple
simultaneus keypresses, as required by most arcade style games.
The MOUSE functions provide a very simple interface to the mouse
driver. They are not much more that names to the INT 33 functions.
Using the lowlevel sprite functions
===================================
Initializing
------------
The first thing to do in a program which uses the STK is to
start the graphics mode and initialize the sprites. This is done
by the functions gr_detect, gr_start and spr_initialize (for
further information, see The STK Function Reference). Now we are
ready to use the STK functions.
Creating and destroying sprites
-------------------------------
The sprites are represented by SPRITE handles. The exact definition
of the object pointed by a handle is private to the STK
implementation, therefore the sprites can be manipulated only
with the provided functions.
Each sprite has a shape defined by a sprite map. These can be
created by the SPRED sprite editor. Each sprite map contains the
actual shape of the sprite and the mask which describe the
transparent parts of the sprite.
We must create sprites before we can do anything with them. This
is done with the function spr_create, if we have the sprite
shape bitmaps in static arrays, or with the function
spr_fio_read_smp if the shape is in a sprite map file. Both of
these functions return a SPRITE handle. You can make copies of
sprites by the spr_copy function (you should spr_share the
sprite first to save memory, since copies of shared sprites
share the shape data which can take quite much memory).
The sprite resolution parameter in the spr_create means the
number of shifted images per 8 pixels, ie 4 means that the X
coordinates 0 and 1 will map into the same screen position. Try
giving a numeric parameter (1,2,4,8) to the StarMines program to
see the effect of resolution parameter (for example "sm 4").
Each sprite should be though of as an object with its own
identity and properties like the current location, the shape
data and the identifier. If you need many sprites with the same
shape, you should use the spr_copy to make copies, NOT to try to
display the same sprite many times at different locations.
When the sprite is no longer needed it should be destroyed with
the spr_delete function, which releases all the resources used
by the sprite.
How much memory do we need
--------------------------
A sprite which is W bytes wide and H scanlines tall and uses
sprite resolution S takes 2*S*((W+1)*H) + 2*(W+1)*H bytes of
memory from far heap and only about 40 bytes from the near heap.
This means that the small memory model is big enough in most
applications.
Example: the sprite is 32 pixels (4 bytes) wide, 24 pixels tall
and we want the best resolution (8). The sprite will need
2*8*((4+1)*24) + 2*(4+1)*24 = 2160 bytes memory.
The memory consumption is one of the reasons why my sprites are
monochrome, they would need 4 times as much memory (in the
example over 8 kbytes for one sprite!) if they had 16 colors.
Also the output would be four times slower making it impossible
to use one pixel resolution in movements with anything slower
than 16 MHz.
If sharing is used then the N copies will take 2*S*((W+1)*H) +
2*(W+1)*H*N bytes of memory from the far heap plus those 40
bytes of near heap for each copy.
Manipulating sprites
--------------------
A sprite can be put into the screen with the function spr_put.
A sprite which has been put into the screen can be hidden by the
function spr_hide. Displaying and hiding sprites do not take
place immediately, but only after the next call to the function
spr_next_pass. This function should be called in the main loop
of the program after all sprites have been spr_put into their
current positions.
What the spr_next_pass really does? It draws all the sprites
which have been spr_put after the previous spr_next_pass into
the hidden display page (and saves the background below them).
Then that display page is activated and the sprites which are in
the now-hidden page are deleted by restoring the previously
saved background data. Therefore you must spr_put the sprites
during every pass of the main loop of the program.
The method described above makes it possible to achieve
reasonably fast flicker-free animation. There is a problem with
this approach: EGA graphics cards are slow changing video pages,
and therefore we must waste about 10 milliseconds waiting after
the screen flip. Hercules cards do not need this wait-state,
therefore Hercules mode is preferred in slower machines. Note
that this wait-state affects the frame speed, and it should be
regulated with the spr_regulate_speed function.
The collision detection should be done after all the sprites
have been spr_put but before the spr_next_pass. It is possible
to either check the collision between a sprite and a coordinate
position, the collision between two sprites (spr_hit) or find
all the sprites a given sprite collides (spr_hit_first and
spr_hit_next). All collisions are first checked by the bounding
box and after that by using the mask map of the sprite.
You can retrieve information about a given sprite by the
functions spr_get_id, spr_get_x, spr_get_y, spr_get_width and
spr_get_height.
Using the higher level sprite functions
=======================================
Creating and destroying animated sprites
----------------------------------------
The animated sprites are represented by ANIM_SPRITE handles. The
exact definition of the object pointed by a handle is private to
the STK implementation, therefore the sprites can be manipulated
only with the provided functions.
The ANIM_SPRITEs are created by the function spr_anim_create.
This function takes simple sprites as parameters. These should
have been generated earlier, for example by the function
spr_create. Note that you must have different instances of
simple sprites for each animated sprite you create.
An animated sprite is deleted by the function spr_anim_delete.
This function will not delete the simple sprites it contains. If
also the simple sprites need to be deleted the function
spr_anim_destroy must be use